NRLS Record Locator Service

RESTful API Architecture

The NRLS REST API is a constrained version of the HL7 FHIR DSTU2 RESTful API.

This section provides an overview of the Spine 2 NRLS FHIR interface. The objective of Sprint 2 is to specify a first draft of RESTful FHIR API design approaches to the following proof of concept NRLS use cases:

  • UC-1 Register a locally held Patient Document on the NRLS
  • UC-2 Remove a NRLS Record
  • UC-3 Search for Patient Documents using the NRLS

NB: Business rules have NOT yet been agreed for these use cases.

Spine Integration Pre-requisites

For all use cases described, it is assumed that NRLS client systems will be capable of performing Patient Demographic Service (PDS) tracing of patients to obtain NHS Number, Date of Birth and current GP organisation.

NRLS FHIR Conformance statement

The NRLS FHIR conformance statement defines the expected capabilities of the server that will provide the FHIR RESTful functionality of the NRLS. The DRAFT NRLS-Conformance-1-0 profile represents the NRLS FHIR conformance statement. It is a constrained version of the HL7 FHIR DSTU2 Conformance resource and is published as a 'work in progress' version and as such is subject to change.

Example Conformance Interactions:

A conformance interaction will retrieve the NRLS FHIR server conformance statement. The interaction is performed by an HTTP GET or OPTIONS command as shown: 

GET [base]/metadata {?_format=[mime-type]}
OPTIONS [base] {?_format=[mime-type]}

Pre-requisite PDS Interaction:

Get Patient using the PDS Mini Services Spine FHIR interface. This call uses the NHS Number to find the patient on PDS. If a patient is successfully traced, the PDS will return a bundle with Patient (including logical id) and GP Organisation resources.

Example HTTP GET Patient operation:

HTTP GET command used to retrieve the Patient and GP Organisation resources on PDS Mini Services using the parameters 'NHS Number' and '_include=Patient:careprovider', encoded in the URL:

GET [base]/Patient?identifier=http://fhir.nhs.net/Id/nhs-number|7021341152&_include=Patient:careprovider

NRLS Sprint 2 RESTful FHIR Interactions

structure

UC-1 Register a locally held Patient Document on the NRLS

For the pilot, this use case is concerned with the functionality to allow a suitable user or system to register a locally held EPaCCs record on the NRLS. The full detail of the patient EPaCCs Record will not be stored within the NRLS EPaCCs record.

The "Register NRLS Record" API uses the 'create' RESTful FHIR interaction (aka operation) to register that a patient's EPaCCs record is available to NRLS consumer systems. The registry will only record meta data about the record that is being registered on the NRLS e.g. document type, document author, document created/ registered dates and the URL of the referenced document etc.

The 'create' interaction is performed by an HTTP POST of the NRLS-DocumentReference-1-0 resource to the NRLS Registry endpoint.

Example 'Register NRLS Record' HTTP POST operation:

HTTP POST command is shown:

POST [base]/DocumentReference

Assuming successful URL submission, there are several possible responses to the registry request:

  • HTTP 201-Record Created: The entry has been successfully created and the NRLS returns an HTTP Location header containing the 'server' assigned logical Id of the created resource.
  • HTTP 400-Bad Request: Resource could not be parsed or failed basic FHIR validation rules
  • HTTP 404-Not Found: Resource type not supported, or not a FHIR end-point
  • HTTP 422-Unprocessable Entity: The proposed resource violated applicable FHIR profiles or server business rules.

UC-2 Remove a NRLS Record

For the pilot, this use case relates to functionality to allow a clinical user or EPaCCs System to remove a NRLS EPaCCs record/ make a reference to one or more EPaCCs records on the NRLS unavailable. This may be for a number of reasons including:

  1. One of more patient EPaCCs records have been deleted / removed from the local EPaCCs system.
  2. The patient may have dissented to share any records referenced on NRLS.

The "Remove NRLS Record" API uses either a RESTful 'delete' or a 'conditional delete' interaction (with no request body) to remove a NRLS-DocumentReference-1-0 from the registry, making that record unavailable via record discovery.

Example HTTP DELETE operation:

HTTP DELETE command that removes an existing resource by logical id:

DELETE [base]/DocumentReference/69372

NB: The custodian/ contributer system MUST use the NRLS assigned logical id to delete the NRLS-DocumentReference-1-0 from the registry.

Example HTTP (Conditional) DELETE operations:

The conditional delete interaction allows a client to delete an existing resource based on parameters encoded within the URL, rather than by a specific logical id.

HTTP DELETE command with a parameter of 'NHS Number' encoded in the URL:

DELETE [base]/DocumentReference?subject=[base]/Patient/7021341152

HTTP DELETE command with chain parameters 'NHS Number' and 'Document Type' encoded in the URL:

DELETE [base]/DocumentReference?subject=[base]/Patient/7021341152&type.coding=http://snomed.info/sct|861421000000109

HTTP DELETE command with chain parameters 'NHS Number' and 'index date' encoded in the URL:

DELETE [base]/DocumentReference?subject=[base]/Patient/7021341152&indexed=<=2016-01-01

Assuming successful URL submission, there are two possible outcomes to the delete request:

  • HTTP 204-No Content: The record either does not exist or has been successfully deleted.
  • HTTP 404-No match to delete: The parameters used to identify the record were not met.

NB: Server conformance (such as Multiple matches and version history) has NOT yet been agreed for deletion of NRLS records.

UC-3 Search for Patient Documents using the NRLS

For the pilot, this use case relates to the process of:

  1. Users and systems using the NRLS to search for Patient Documents associated with a specific patient.
  2. The NRLS presenting a flag / search results indicating that a patient has one or more locally held Patient Documents.

These search results will include relevant metadata about the Patient Document information that signposts / directs the user to the full detail of the Patient Document. Metadata will include:

  • Type of Patient Document
  • Author of Patient Document
  • Date and time Patient Document created / updated
  • Date and time Patient Document registered on the NRLS
  • A URL that will allow an Accessing Clinical User to access the full detail of the Patient Document referenced by the NRLS

The "Discover NRLS Record" API comprises RESTful search interactions using the HTTP GET command:

Example Discover NRLS Record HTTP GET operations:

HTTP GET command with the referenced Patient 'logical id' as the subject, and the _elements parameter consisting of the base element 'content':

GET [base]/DocumentReference?subject=[base]/Patient/69372&_elements=content

HTTP GET command with the simple search parameter 'NHS Number', encoded in the URL:

GET [base]/DocumentReference?subject=[base]/Patient/7021341152

HTTP GET command with the chained query parameters 'NHS Number' and 'Document type', encoded in the URL:

GET [base]/DocumentReference?subject=[base]/Patient/7021341152&type.coding=http://snomed.info/sct|861421000000109

HTTP GET command with the chained query parameters 'Practitioner logical id' and 'Organization logical id', encoded in the URL:

GET [base]/DocumentReference?author=[base]/Practitioner/69373&custodian=[base]/Organization/69374

HTTP GET command with the simple search parameter 'created date', encoded in the URL:

GET [base]/DocumentReference?created=2016-03-08

HTTP GET command with the simple date/time range search parameters (using parameter value prefixes), encoded in the URL:

GET [base]/DocumentReference?created=ge2016-03-08&created=le2016-03-25

Assuming successful URL submission, there is one possible outcome to a search request:

  • HTTP 200-Request was successfully executed

The NRLS server determines which of the set of resources it serves meet the specific criteria, and returns the results of the search e.g. NRLS-DocumentReference-1-0 in the HTTP response as a 'searchset' bundle.

Note: Although an HTTP response 200 OK indicates the request was successful, the bundle could return a 0 (zero) total value indicating no record was found. This is an XML example of the Bundle with a 0 (zero) total value indicating no record was found.

Paging

If the result list of a NRLS FHIR RESTful search interaction is long, the FHIR server, may use paging to break up this result list. It is proposed that the FHIR server will conform to this method RFC 5005 (Feed Paging and Archiving) for sending continuation links to the client when returning a search Bundle.

Managing Return Errors

The Spine-OperationOutcome-1-0 resource profile can be used to convey specific detailed processable error information e.g. it may be returned with any HTTP 4xx or 5xx responses.